home *** CD-ROM | disk | FTP | other *** search
/ Animation / Animation Vol.1 (Profi ROM)(1994).iso / pvquan15 / pvquan.doc < prev    next >
Text File  |  1992-04-05  |  30KB  |  696 lines
  1.  
  2.                           PVQUANT Version 1.50
  3.  
  4.                            A Colour Quantiser
  5.                                 for the
  6.                     Persistence of Vision Raytracer
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23. Written and Distributed by:
  24.  
  25. Frank van der Hulst,
  26. 101 Epuni St,
  27. Lower Hutt,
  28. New Zealand
  29.  
  30. Electronic mail to:
  31. UseNet:   frank@cit.ac.nz, frank@whare.cavebbs.gen.nz
  32. FidoNet:  frank vanderhulst at GenBoard (Node 3:771/160)
  33.  
  34. 03 April 1992
  35. ───────────────────────────────────────────────────────────────────────────
  36.  
  37. These programs are freely distributable.  The authors retain the
  38. copyright to the program but authorizes free distribution by BBS'es,
  39. networks, magnetic media, etc.  The distributor may charge no more than
  40. five dollars ($5) U.S. for this software.
  41.  
  42. The images and data files generated by these programs are the property
  43. of the user of the software and may be used for any purpose without
  44. restriction.
  45.  
  46. The authors make no guarantees or warranties with these programs and
  47. claim no responsibility for any damage or loss of time caused by this
  48. program. Bug reports may be sent to the authors but the authors are
  49. under no obligation to provide bug fixes, features, or any support for
  50. this software.
  51.  
  52. The following conditions are placed on the use of this program:
  53.  
  54. 1) That it should not be used as part of any commercial package without
  55.     the explicit written consent of the author.
  56.  
  57. 2) If you make any changes to the source code, please let me know.
  58.     That's the way this program was built!
  59.  
  60. 3) This text file must accompany the program.
  61.  
  62. This manual is divided into the following sections:
  63.  
  64.    1) Archive Description
  65.    2) Background
  66.    3) Getting Started
  67.    4) Command Line Parameters
  68.    5) Output File Format
  69.    6) Source Code Information
  70.    7) Displaying the Images
  71.    8) Animation
  72.    9) Compiling the Code
  73.   10) Porting to Different Platforms
  74.  
  75. 1) Archive Description
  76. ~~~~~~~~~~~~~~~~~~~~~~
  77. This archive contains C source code for a set of programs to convert
  78. image files produced by DKB-Trace or Persistence of Vision raytracer
  79. into a format suitable for display on a VGA screen, or to GIF format. It
  80. includes programs to generate a single stereoscopic 3D image from two
  81. views of a scene, as well as programs to produce animation from multiple
  82. ray-traced images.
  83.  
  84. The programs (or large parts of them) were written by several different
  85. people. All of the programs are in the public domain to some extent,
  86. with some restrictions put on them by their respective authors. I have
  87. collected these from various places, ported them to Turbo-C and GNU C if
  88. necessary, and formatted them in a way that I like. The copyright for
  89. each program still belongs to its author -- my copyright claim extends
  90. only to the collection of programs (like the editor of a journal, for
  91. example).
  92.  
  93. QUANT (HECKBERT & OCTREE):
  94.   Colour quantisation program which post-processes raw image files
  95.   produced by the Persistence of Vision Ray Tracer (PoV Ray). Two
  96.   versions can be compiled: one uses Heckbert's median-splitting
  97.   algorithm, whereas the other uses Octree quantisation.
  98.  
  99. DISPLAY:
  100.   Displays either 320x400 or 320x200 images, either 2D, or stereo 3D. 3D
  101.   images require Sega 3D-glasses to be connected to the serial port for
  102.   viewing.
  103.  
  104. MAKEANIM:
  105.   Reads an animation source file (*.ANM), and uses it to generate data
  106.   files for the PoV ray tracer.
  107.  
  108. ANIMGIF:
  109.   Produces a .GIF file containing a series of images to be displayed by
  110.   ANIM.
  111.  
  112. ANIMFLI:
  113.   Produces a .FLI file containing a series of images to be displayed by
  114.   a .FLI player (e.g. Autodesk's AAPLAY).
  115.  
  116. ANIM:
  117.    Produces animation on a 320*200 screen using page flipping, including
  118.    sound.
  119.  
  120. Files contained in this archive:
  121. -------------------------------
  122. QUANT.ZIP     Quantiser source code
  123. PAC_BASE.DAT  Sample PoVRay data file for generating animation
  124. SHAPES.DAT    Required to produce sample animation image
  125. MAZE.IFF      Required to produce sample animation image
  126. INCLUDE.ZIP   To be unzipped to C include directory
  127. VGA.ZIP       VGA 320x200x256x4 & 320x400x256x2 driver source code
  128. GIFLIB.ZIP    GIF encoding/decoding
  129. ANIM.SH       Unix shell script for generating animation
  130. TRACE.SH      Unix shell script to run ANIM.SH as background task
  131. PACMAN.ANM    Sample animation script
  132. ANIM.ZIP      Animation source code
  133. QUANT.DOC     Documentation
  134. README        This file
  135. FLILIB.ZIP    FLI creation routines
  136.  
  137. 2) Background
  138. ~~~~~~~~~~~~~
  139. I have a 286 PC clone with a VGA screen, and am interested in virtual
  140. reality. I realise that a 286 doesn't have the horsepower to be good for
  141. that, but that's all I got. Attached to this I have a pair of Sega 3D
  142. glasses, which allows me to view see a 3D image by displaying
  143. stereoscopic pairs of images on the screen.
  144.  
  145. I started off drawing images with Turbo C, but that was time-consuming
  146. and not very effective. I then got a copy of DBW_RENDER and used it
  147. (over many nights over many weeks) to produce images. In the meantime,
  148. Craig Kolb had sent me a copy of his COLORQUANT code, which I ported to
  149. Turbo C. I also found code to display images in 320x400 mode on my VGA.
  150. Finally I could display some good images. I modified the quantiser to
  151. read two input files to produce one palette, so that I could display a
  152. 3D image.
  153.  
  154. The primitives available in DBW_RENDER were very limited, so I switched
  155. to DKB-TRACE v2.12. And ran my machine day and night for months.
  156.  
  157. Then I got access to a 486 running SCO Unix. Great! My 286 took a rest
  158. at nights, because I could generate the most complex scenes in only a
  159. few hours. Unfortunately, I couldn't display the images, or even move
  160. them easily from the 486 (the only direct interchange medium is 360K
  161. floppies, and the QRT-format files are too big). Also working with the
  162. QRT-format was clumsy, so I converted the quantiser to read raw format
  163. files (each of which is only 128K long, thus easily transported). Then I
  164. saw a copy of the Octree quantisation code on UseNet, so I tried that.
  165. It was much faster (a real advantage on the PC) but produced inferior
  166. results. Next step was to move the quantiser to Unix, and suddenly the
  167. Heckbert technique was best.
  168.  
  169. The extra speed of the Unix box opened up some new possibilities -- I
  170. started to look at animation. I could generate about seven images per
  171. hour, then use a display program to flip them up one by one. That works
  172. fine (although it needs a lot of memory on the PC).
  173.  
  174. Then I received an assembler source file by K. Heidenstrom which did
  175. page flipping in 320*200*256 mode. This makes animation easier, since
  176. each image requires less memory. It also makes 3D animation possible.
  177.  
  178. Now I have easier access to a Sun IPC workstation than the the '486 --
  179. so I've ported the raytracer and other files to compile using the GNU C
  180. compiler gcc.
  181.  
  182. The GIF display program needs lots of memory, and the files (even after
  183. GIF compression) are huge... the GIF standard isn't well suited to
  184. animation. So I took the FLILIB source from Simtel... that was designed
  185. to be compiled on the PC using TurboC (included was 8086 assembler
  186. source code to open and close files, amongst other things). I ported
  187. that to gcc, converting things back to C and fixing some annoying
  188. pointer addressing problems.
  189.  
  190. Next is Floyd-Steinberg dithering, to remove unwanted "banding" of
  191. coloured regions (called false contours).
  192.  
  193. Or maybe adding sound to a FLI player. Or perhaps 3d animation....
  194.  
  195. 3) Getting Started
  196. ~~~~~~~~~~~~~~~~~~
  197. Before quantising an image, you must create one! Use either DKB-TRACE or
  198. PoVRAY to produce output in the "Targa" format.
  199.  
  200. I use the following command line:
  201.         PVRAY -ipacman.dat -opacman.tga -w320 -h400 -v +ft +p +x -a
  202.  
  203. See the raytracer documentation on what all the above mean. Most
  204. important is the "+ft" option which tells the raytracer to produce
  205. "Targa" files. The quantiser can also read "raw" format files (use the
  206. "+fr" switch). If you use this (there's no real reason why you should)
  207. and run PVRAY on a PC, you'll probably need to rename the files
  208. produced. By default it